<html xmlns="http://www.w3.org/1999/xhtml">
<head>
</head>
<body>

<!-- ===================================================================== -->
<!-- = XML information goes here                                         = -->
<!-- ===================================================================== -->
<lzelement title="Multistatebutton">
    <lztier>Base Component</lztier>
    <lzcategory>View</lzcategory>
    <lzshortdesc>
        a button with multiple states, such as a toggle button
    </lzshortdesc>
    <lztag>base/multistatebutton.xml</lztag>
</lzelement>

<p>A <classname>multistatebutton</classname> is an extension of the
<classname>basebutton</classname> class to address the more general
class of buttons that can have multiple states, and where each state
has it own mouseup, mouseover, and mousedown images. Like the
<classname>basebutton</classname> class, the construction of a
<classname>multistatebutton</classname> starts with a multiframe
resource.</p>

<p>The example below create a play/pause button, using the following
resources:</p>

<img src="images/multistatebutton/state0-mouseup.jpg" width="40" height="40" />
<img src="images/multistatebutton/state0-mouseover.jpg" width="40" height="40" />
<img src="images/multistatebutton/state0-mousedown.jpg" width="40" height="40" />
<img src="images/multistatebutton/state1-mouseup.jpg" width="40" height="40" />
<img src="images/multistatebutton/state1-mouseover.jpg" width="40" height="40" />
<img src="images/multistatebutton/state1-mousedown.jpg" width="40" height="40" />

<p>With a multistatebutton, the following must be specified explicitly:</p>

<dl>
<dt>statenum</dt>
<dd>the initial state of a button</dd>
<dt>statelength</dt>
<dd>the number of frames (of a multiframe resource) used for a single button state - NOTE: all states must be the same length</dd>
<dt>maxstate</dt>
<dd>the total number of states of the button - 1  (since states are counted starting from 0).</dd>
</dl>

<example filename="multistatebutton-resources.lzx" executable="false">
&lt;library&gt;
  &lt;!-- first create the multi-frame resource and give it a name --&gt;
  &lt;resource name="mybutton_rsrc"&gt;
     &lt;!--  State: 0 --&gt;
     &lt;!-- first  frame of state 1 = mouseup   image of the button --&gt;
     &lt;frame src="images/multistatebutton/state0-mouseup.jpg"/&gt;
     &lt;!-- second frame of state 1 = mouseover image of the button --&gt;
     &lt;frame src="images/multistatebutton/state0-mouseover.jpg"/&gt;
     &lt;!-- third  frame of state 1 = mousedown image of the button --&gt;
     &lt;frame src="images/multistatebutton/state0-mousedown.jpg"/&gt;

     &lt;!--  State: 1 --&gt;
     &lt;!-- first  frame of state 2 = mouseup image of the button --&gt;
     &lt;frame src="images/multistatebutton/state1-mouseup.jpg"/&gt;
     &lt;!-- second frame of state 2 = mouseover image of the button --&gt;
     &lt;frame src="images/multistatebutton/state1-mouseover.jpg"/&gt;
     &lt;!-- third  frame of state 2 = mousedown image of the button --&gt;
     &lt;frame src="images/multistatebutton/state1-mousedown.jpg"/&gt;
  &lt;/resource&gt;
&lt;/library&gt;
</example>
  
<example title="Assigning resources to a button">
&lt;canvas height="60"&gt;
  &lt;include href="multistatebutton-resources.lzx"/&gt;

  &lt;!-- Second, assign the resource to a basebutton tag --&gt;
  &lt;multistatebutton name="myButton" resource="mybutton_rsrc"
                    statenum="0" statelength="3" maxstate="1"/&gt;
&lt;/canvas&gt;
</example>

<p>Now, the multistatebutton will stay in state "0" until you switch
states. This can be accomplished by calling
<code>myButton.setStateNum(number)</code>.</p>

<example title="Switching button states">
&lt;canvas height="60"&gt;
  &lt;include href="multistatebutton-resources.lzx"/&gt;
  
  &lt;multistatebutton name="myButton" resource="mybutton_rsrc"
                    statenum="0" statelength="3" maxstate="1"
                    onclick="this.toggle()"&gt;
     &lt;method name="toggle"&gt;
        if (this.statenum == 0) this.setStateNum(1)
        else this.setStateNum(0)
     &lt;/method&gt;
  &lt;/multistatebutton&gt;
&lt;/canvas&gt;
</example>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
